Mercutio 1.1 is a replacement for the standard menu definition routine that supports menu item key equivalents with multiple-modifier keys (e.g. command-option). It allows four combinations of modifier keys: command, command-option, command-shift, and command-option-shift.
- System 7's Balloon Help and True Gray.
- Color menus.
- Small and large icons.
- SICNs in hierarchical menu items.
- 99% compatible with standard MDEF: the
only thing Mercutio doesn't do is support
the "condense" and "extended" character styles.
There are three steps to using Mercutio: (1) building your menus, (2) calling it from your program, and (3) installing the necessary resources into your application.
1. Mercutio uses standard MENU resources but interprets the style field of the menu items slightly differently than the standard MDEF. In particular, the condense attribute is taken to mean the modifiers for this item are "command-option", and the extended attribute is taken to mean "command-shift". If both are set, the modifiers are "command-option-shift". If neither is set, but a character is specified in the key equivalent field, the modifier is simply "command".
The symbols for option and shift are included in the MDEF Font, which is included in this package. This font must be installed for the MDEF to function correctly. These symbols are stored in a font rather than in the MDEF itself to allow for future expandability and compatibility.
2. In order to correctly interpret the user's keypresses, we need a replacement for the toolbox MenuKey routine that checks for multiple modifier keys. The PowerMenuKey routine included in the Mercutio API.p file provides this support.
FUNCTION PowerMenuKey (theMessage: longint;
theModifiers: integer;
hMenu: menuHandle): longint;
PowerMenuKey takes the message and modifiers fields from the standard event record as inputs, and returns a longint in the same format as MenuKey's result: the high word contains the Menu ID, the low word contains the menu item number. If no items match the message-modifiers combination, PowerMenuKey returns 0.
You must pass in a menuHandle to any menu that uses the Mercutio MDEF for this routine to work. If you pass in NIL or a menu driven by the system MDEF instead, PowerMenuKey uses the standard MenuKey toolbox routine to interpret the user's keypress.
The Pascal and C source for PowerMenuKey is provided for you in case you want to modify it or translate it into another language. Please include the copyright notice with all modifications.
3. The following resources are needed:
Type ID Name Comments
MDEF 1 Mercutio The code itself
FOND 32256 .MDEF Font Font containing key symbols and arrows
NFNT 32000 .MDEF Font Ditto
All resources are named "Mercutio", and can be found in the "Mercutio! 1.1.mdef" file included in this package.
Here's how Mercutio differs from the standard MDEF:
1. Mercutio supports both ICON and SICN resources (the standard MDEF supports only ICON resource). If the icon ID field contains a valid number n (range 1 to 255), the following occurs:
- if the keyEquivalent field contains $1D, it will look for a 'cicn' (or
an 'ICON' if no color icon is found) of ID (n+256), and draw it as a
reduced icon (16 x 16).
- if the keyEquivalent field contains $1E, it will look for a 'sicn'
resource of ID (n+256), and draw it its normal size. (16 x 16).
- if the keyEquivalent field contains anything else, it will look for
a 'cicn' (or an 'ICON' if no color icon is found) of ID (n+256), and
draw it normal size.
The only exception is for icon ID's ranging from 500 to 512 (that is, the iconID field in the menu item ranges from 243 to 255). These icons are "always" drawn small (16 x 16). This allows you to have small icons in hierarchical items (where you can't use the keyEquivalent field to request a small icon since it must be $1B to flag a hierarchical menu).
2. Mercutio interprets the 'extend' and 'condense' attributes as option and shift flags.
These are some guidelines I made for myself once I started using this MDEF. You may find them useful when deciding how to integrate multiple modifier key equivalents in your menus.
• Use multiple-modifiers sparingly. Avoid the temptation to provide a
key equivalent for every menu item simply because the capability
is there…
• Keep menu items with similar modifiers grouped together in the
menus.
• Keep multiply-modifiers functionally related. I suggest two ways
of doing this:
1. Make multiple-modifiers variations of single-modifiers.
For example, command-S is "Save" so option-command-S
would be "Save As…".
2. Make multiple-modifiers related to each other according
to what modifiers are used. For example, shift-command-B
is "Bold", shift-command-I is "Italic", shift-command-U is
"Underline, etc., so that the user accesses formatting short-
cuts using the shift-command sequence.
This release of Mercutio is a toned-down version of an earlier one which allows a wider variety of modifier keys (e.g. option-control without necessary holding down the command key). It became apparent that the addition of option- and shift- support would satisfy most application needs, and that too much freedom in combination selection might lead to more severe violations of the human interface guidelines.
I spend several months agonizing over the most elegant way to implement this MDEF. Unfortunately, my two primary goals, "keep it compatible" and "make it simple and easy to use", seemed to conflict with each other: if I kept it completely compatibly with the standard MENU resource format, there was no room to store the information about the modifier keys; and if I blatantly grabbed one of the MENU fields (e.g. the icon field) to store the modifier info, it became harder to create menus since the standard MENU editing templates didn't work anymore. I settled on this scheme because it seemed the least obtrusive, and was completely compatible with all MENU editors. If anyone has a suggestion for a better way to do it, I'm eager to hear of it!
The keyboard symbols are in a font (rather than SICNs) to take advantage of the Font Manager's spacing capabilities. The symbols for the modifier keys do not need to be the same width, so making them characters in a font let me print several in a row without doing hairy spacing measurements.
• 7/28/93 : 1.1.5
- Fixed Key equivalent conflict for menu items with the same command-key
- Fixed Key equivalent conflict for disabled menu items
• 1/20/93 : 1.1.4
- Public release of 1.1.4
- Fixed bug in erasing menu background (Mercutio now works with Greg’s Buttons)
- Fixed bug in PopupMsg (Mercutio now works with popup menus)
• 10/19/92 : 1.1.3
- Added procedural support to retrieve Mercution version and copyright information.
• 10/19/92 : 1.1.2
- Built and tested C API.
- Fixed bug in non-resource menus (Mercutio now works with menus built on the fly).
• 11/13/92 : 1.1.1
- Fixed bug in keyboard mapping (Mercutio now works with Dvorak keyboard layouts).
• 10/19/92 : 1.1
- Released!.
Mercutio is freeware but not public domain. It may be copied and distributed freely as long as no modifications are made to it and nothing is charged for it. You may use it free of charge in any project of yours provided:
in an About box or other appropriately visible place)
(2) you send me a full copy of the finished product (electronically
or via U.S. Mail).
If you can't abide by these terms, but would still like to use the Mercutio MDEF, contact me and maybe we can work something out.
The API files include two routines that retrieve the Copyright and Version information embedded in the Mercutio MDEF. You can use these to pull out the exact information to be displayed in the About box.
As always, feedback, comments and bug reports are happily accepted. I will try to fix bugs as soon as I get them, and will try to support whatever features people request in subsequent releases of Mercutio. I can be reached at any of the following e-mail addresses:
Internet : felciano@summit.stanford.edu
Applelink : SUMMIT
America Online : SUMMITDev
Compuserve : 76166,3627
or via U.S. Mail at:
Ramon M. Felciano
1326 Masonic Ave.
San Francisco, CA 94117
Special thanks to John Cavallino for providing invaluable feedback, technical advice and patience.
